Instructions for Twistory 2.1

About TTT Resources

      Twistory comes with a folder of text resources called "ttt" and an index file called something like "index.ttt." Double-click on this file to open Twistory.

     The files in the "ttt" folder are of two types, identified by their filename extensions. The extension ".ttt" stands for "twistory text." These files contain information on places, people and events. There are also files with the extension ".geo" which are actually just ".ttt" files, but which are so named as a comment that they contain only place data. (You can actually call the files anything you want.)

     The other kind of file has the extension ".poly" for "polygon." These are also text files, but are most easily created and edited with a separate program called PolyTool, which is included with this release.

     The following sections describe the format of the ".ttt" files. The characters "#," "<" and ">" are reserved. They may only be used as documented below. "C++ and C-style" comments may also be used. Here are examples of comments, which are ignored when Twistory reads a file:

This is not a comment.  /* This "C-type" comment begins and ends with an oblique
and an asterisk, which are reversed at the end. */  This is not a comment.
This is not a comment.  //  This "C++-type" comment begins with two obliques, and goes to the end of the line.
//  This is a comment.
This is not a comment.

     To allow that characters #, < and > to be used in certain strings, such as the "info" string or the name of an event, you may use the entities &pound;, &lt; and &gt;.

The File Mark-up: #file

     Twistory files are arranged in a hierarchy, and this markup is used to link them together. An index file (which can have any name) is used to list all files or sub-index files. As Twistory reads any file, if it finds the sequence "#file" it suspends reading the file it is in and opens the file whose name appears after the "#file" markup. The format is as follows:

#file "ttt/egypt.ttt"

This tells Twistory to look in the folder "ttt" for a file called "egypt.ttt" and to read its contents in right away, before finishing the current file.

     The order in which files are listed in the index, and the order in which items appear in the files, is significant. For example, a place description must be read in before it is referred to in a person record.

The Era Mark-ups: #bc and #ad

     These mark-ups have no fields, and are used to change the default era for dates. A change in the default era made within a file is forgotten once that file ends and reading returns to a file which is higher up the hierarchy. But a change is passed down to a lower file. The safest practice is to specify either #bc or #ad at the beginning of every file.

Mark-ups for Historical Items: #c, #i, #p, #e and #s

     The five remaining mark-ups in the .ttt file format are #c[ity], #i[tem], #p[erson], #e[vent], and #s[phere]. Only the first letter of each is needed. These mark-ups each signal the beginning of a different type of data record.